Mini curso: Quarto y GitHub Pages

III Jornadas de Ingeniería Estadística 2024
11 y 12 de Noviembre 2024, Auditorio DMCC
Universidad de Santiago de Chile 		Logo JIE

Francisco Plaza Vega
francisco.plaza.v@usach.cl

USACH

Introducción

¿Qué es la Investigación Reproducible?

Es la práctica de conducir estudios científicos o basados en datos de tal manera que permita a otros replicar o reproducir los resultados usando los mismos datos, códigos y metodologías.

Etapas de una Investigación Reproducible

Ciencia Abierta

Espectro de Reproducibilidad

Qué necesitaremos?

Repositorio

Enlaces importantes

Sofware necesarios

R project

https://cran.dcc.uchile.cl/

RSudio IDE

https://posit.co/download/rstudio-desktop/

Existen otras alternativas más génericas como Visual Studio Code, un editor de código para múltiples lenguajes. Sin embargo, al no ser un software especializado en R, requiere utilizar extensiones para lograr las funcionalidad que otorga RStudio.

Quarto

https://quarto.org/docs/get-started/

Git & Github

Quarto

Rmarkdown & Quarto

El paquete rmarkdown provee un marco de escritura para investigaciones cuentitativas, que combina códigos, resultados y texto. Los documento R Markdown son completamente reproducibles y permiten generar archivos en distintos formatos: PDF, Word, Presentaciones y más. Quarto es la nueva generación de esta herramienta para incluir distintos lenguajes.

Algunos ejemplos

Quarto

Los archivos Quarto fueron diseñados para ser usados de tres maneras:

  1. Para comunicar a los tomadores de decisiones, quienes quieren centrarse en las conclusiones, no en el código detrás del análisis.

  2. Para colaborar con otros investigadores, quienes están interesados en las conclusiones y el cómo se llego a ellas (i.e. el código)

  3. Como un ambiente para hacer análisis, como un notebook donde se puede capturar el trabajo realizado junto a notas de este.

Primeros pasos

  1. Entrar a Quarto.org
  2. Descargar Quarto para tu sistema operativo
  3. Ingresar a RStudio y crear documento .qmd

Flujo documento Quarto

  • qmd: archivo de origen
  • knitr: Herramienta que interpreta y ejecuta códigos y lo traduce en texto markdown
  • md: texto escrito en lenguaje markdown
  • pandoc: Herramienta que convierte archivos .md enb distintos formatos

Anatomía de un documento Quarto

  1. Encabezado en formato YAML
  2. Texto en formato Quarto
  3. Bloques de código (R, Python, Julia, Observable)

YAML

YAML es un formato de serialización de datos que puede ser leído fácilmente. Su uso es amplio, desde Acciones en GitHub hasta Quarto

Un ejemplo de YAML que difine un ambiente computacional podría ser:

# Define the operating system as Linux
os: linux

# Use the xenial distribution of Linux
dist: xenial

# Use the programming language Python
language: python

# Use version of Python 3.2
python: 3.2

YAML nos será de particular interés para la creación de documentos y presentaciones reproducibles, utilizando quarto.

Herramientas

El contenido del documento puede estar escrito utilizando diferentes formatos, entre ellos:

  • Quarto
  • HTML
  • LaTeX
  • CSS

Creación de documento básico

  1. Abrir RStudio
  2. File > New File > Quarto Document
  3. Definir características del documento

Markdown

Formato de Texto

Sintáxis Markdown Salida 
*italics*, **bold**, ***bold italics***
 italics, bold, bold italics 
superscript^2^ / subscript~2~
 superscript2 / subscript2 
~~strikethrough~~
 strikethrough 
`verbatim code`
 verbatim code

Encabezados

Sintáxis Markdown Salida 
# Header 1

Header 1

 
## Header 2

Header 2

 
### Header 3

Header 3

 
#### Header 4

Header 4

 
##### Header 5
Header 5
 
###### Header 6
Header 6

Listas

Sintáxis Markdown Salida 
* Lista no ordenada
    + sub-item 1
    + sub-item 2
        - sub-sub-item 1
  • Lista no ordenada
    • sub-item 1
    • sub-item 2
      • sub-sub-item 1
 
*   item 2

    Continuación (4 spaces)

  • item 2

    Continuación (4 spaces)

 
1. Lista ordenada
2. item 2
    i) sub-item 1
         A.  sub-sub-item 1
  1. Lista ordenada
  2. item 2
    1. sub-item 1
      1. sub-sub-item 1

Listas

Sintáxis Markdown Salida 
(@)  Una lista cuyos números

continuan después

(@)  de una interrupción
  1. Una lista cuyos números

continuan después

  1. de una interrupción
 
::: {}
1. Una lista
:::

::: {}
1. Seguida de otra lista
:::
  1. Una lista
  1. Seguida de otra lista
 
término
: definición
término

definición

Tablas

Sintáxis Markdown

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Output

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

Código de fuente

Usamos ``` para delimitar bloques de código:


```
código

```

Podemos agregar un lenguaje para destacar el código:


``` python
1 + 1
```

Pandoc ofrece 140 distintos lenguajes para destacar código.

Guía de referencia

Para una lista exhaustiva de las opciones de formato que tienen los documentos .qmd visitar https://quarto.org/docs/guide/.

Formatos de salida: Documentos

Los formatos de salida más utilizados para documentos creados con Quarto son:

Para cambiar entre estos formatos, basta especificiar la salida deseada en el YAML. Otros formatos posibles:

Formatos de salida: Presentaciones

En Quarto tenemos 3 opciones para presentaciones:

En donde RevealJS es el formato que nos entrega más herramientas. (Esta presentación fue hecha utilizando RevealJS en Quarto)

Caso práctico

Crearemos un mismo documento en distintos formatos

Awesome Quarto

Templates

Este tutorial

Este tutorial usa un template llamado clean. Está disponible en un repositorio en GitHub.